home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994 November: Tool Chest / Dev.CD Nov 94.toast / New System Software Extensions / PlainTalk™ Speech Technologies / Speech Recognition / Documentation / SpeechRecognition.h < prev   
Encoding:
C/C++ Source or Header  |  1994-05-04  |  15.2 KB  |  385 lines  |  [TEXT/MPS ]

  1. /************************************************************
  2.  
  3. Created: Monday, January 27, 1992 at 10:19:57 AM
  4.     SpeechRecognition.h
  5.     
  6.     C Interface to the PlainTalk™ Speech Recognition Toolbox
  7.  
  8.         Copyright Apple Computer, Inc.    1992-1994
  9.         All rights reserved
  10.  
  11. ************************************************************/
  12.  
  13.  
  14. #ifndef        __SPEECHRECOGNITION__
  15. #define        __SPEECHRECOGNITION__
  16.  
  17. #ifndef        __MEMORY__
  18. #include    "Memory.h"
  19. #endif
  20.  
  21. #ifndef    gestaltSpeechRecognitionVersion
  22.  
  23. /* will be going into GestaltEqu.h */
  24.  
  25. #define    gestaltSpeechRecognitionVersion     'srtb'
  26. #define    gestaltSpeechRecognitionAttr        'srta'
  27.  
  28. #define    gestaltDesktopSpeechRecognition        (1L<<0)
  29. #define    gestaltTelephoneSpeechRecognition    (1L<<1)
  30.  
  31. #endif
  32.  
  33.  
  34. /* Error Codes [Speech recognition gets -5100 through -5199] */
  35.  
  36. enum {
  37.     eSRNotAvailable                = -5100,    /* the service requested is not avail or applicable */
  38.     eSRInternalError            = -5101,    /* a system internal or hardware error condition */
  39.     eSRComponentNotFound        = -5102,    /* a needed system resource was not located */
  40.     eSROutOfMemory                = -5103,    /* an out of memory error occurred in MacPlainTalk space */
  41.     eSROutOfTempMemory            = -5104,    /* an out of memory error occurred in Temporary memory space */
  42.     eSRBadParameter                = -5105,    /* an invalid parameter was specified */
  43.     eSRParamOutOfRange            = -5106,    /* when we say 0-100, don't pass in 101. */
  44.     eSRBadSelector                = -5107,    /* an unrecognized selector was specified */
  45.     eSRBufferTooSmall            = -5108,    /* returned from attribute access functions */
  46.     eSRCantTrackClient            = -5109,    /* an error occurred while tracking client process */
  47.     eSRCantGetSRSystem            = -5110,    /* the requested system could not be located/initialized */
  48.     eSRCantSetProperty            = -5111,    /* a non-settable property was specified */
  49.     eSRCantGetProperty            = -5112,    /* a non-gettable property was specified */
  50.     eSRCantSetDuringRecognition    = -5113,    /* the property can't be set while recognition is in progress -- do before or between utterances. */
  51.     eSRAlreadyListening            = -5114,    /* in response to SRStartListening */
  52.     eSRNotListeningState        = -5115,    /* in response to SRStopListening */
  53.     eSRModelMismatch            = -5116,    /* no acoustical models are avail to match request */
  54.     eSRNoClientLanguageModel    = -5117,    /* trying to access a non-specified LanguageModel */
  55.     eSRNoPendingUtterances        = -5118,    /* nothing to continue search on */
  56.     eSRRecognitionAborted        = -5119,    /* an abort error occurred during search */
  57.     eSRRecognitionDone            = -5120,    /* search has finished, but nothing was recognized */
  58.     eSRBadObject                = -5121,    /* expecting an object as specified in API */
  59.     eSRHasNoSubItems            = -5122,    /* SRCountItems or related routine was called on an object without subelements -- e.g. a word -- rather than phrase, path, or LM. */
  60.     eSRSubItemNotFound            = -5123,    /* returned when accessing a non-existent sub item of a container */
  61.     eSRLanguageModelTooBig        = -5124,    /* Cant build language models so big */
  62.     eSRAlreadyReleased            = -5125,    /* this object has already been released before */
  63.     eSRAlreadyFinished            = -5126,    /* the language model can't be finished twice */
  64.     eSRWordNotFound                = -5127,    /* the spelling couldn't be found in lookup(s) */
  65.     eSRNotFinishedWithRejection    = -5128,    /* property not found because the LMObj is not finished with rejection */
  66.     eSRExpansionTooDeep            = -5129,    /* Language model is left recursive or is embedded too many levels */
  67.     eSRTooManyElements            = -5130,    /* Too many elements added to phrase or path or other langauge model object */
  68.     eSRCantAdd                    = -5131        /* Can't add given type of object to the base LMObject (e.g.in SRAddLMObject)    */
  69. };
  70.  
  71.  
  72. /* Type Definitions */
  73.  
  74. typedef unsigned long SpeechObject;
  75. typedef SpeechObject RecognitionSystem;
  76. typedef SpeechObject Recognizer;
  77. typedef SpeechObject SpeechSource;
  78. typedef SpeechSource RecognitionResult;
  79. typedef SpeechObject LMObject;            /* an LMWord, LMPhrase or LanguageModel */
  80. typedef LMObject LanguageModel;
  81. typedef LMObject LMPath;
  82. typedef LMObject LMPhrase;
  83. typedef LMObject LMWord;
  84. typedef unsigned long LMFlags;
  85. typedef unsigned short SpeedSetting;    /* between 0 and 100 */
  86. typedef unsigned short RejectionLevel;    /* between 0 and 100 */
  87. typedef unsigned long UtteranceLength;    /* a length measure in mS */
  88. typedef unsigned long UtteranceCount;    /* the number of queueable utterances */
  89.  
  90. /* When an event occurs, the user supplied proc will be called with a pointer
  91.     to the param passed in and a flag to indicate conditions such
  92.     as interrupt time or system background time.
  93. */
  94.  
  95. #if defined(powerc) || defined (__powerc)
  96. #pragma options align=mac68k
  97. #endif
  98.  
  99. struct SRCallBackStruct {
  100.     long        what;                /* one of notification flags */
  101.     long        message;            /* contains RecognitionResult id */
  102.     Recognizer    instance;            /* ID of recognizer being notified */
  103.     OSErr        status;                /* result status of last search */
  104.     short        flags;                /* non-zero if occurs during interrupt */
  105. };
  106. typedef struct SRCallBackStruct SRCallBackStruct;
  107.  
  108. #if defined(powerc) || defined(__powerc)
  109. #pragma options align=reset
  110. #endif
  111.  
  112. /* Call back procedure definition */
  113. typedef pascal void (*SRCallBackProcPtr) (SRCallBackStruct *param);
  114.  
  115. #ifndef    USESROUTINEDESCRIPTORS
  116. #define    USESROUTINEDESCRIPTORS 0
  117. #endif
  118.  
  119. #if USESROUTINEDESCRIPTORS
  120. enum {
  121.     uppSRCallBackProcInfo = kPascalStackBased
  122.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(SRCallBackStruct*)))
  123. };
  124.  
  125. typedef UniversalProcPtr SRCallBackUPP;
  126.  
  127. #define CallSRCallBackProc(userRoutine, param)        \
  128.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppSRCallBackProcInfo, (param))
  129. #define NewSRCallBackProc(userRoutine)        \
  130.         (SRCallBackUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppSRCallBackProcInfo, GetCurrentISA())
  131. #else
  132. typedef SRCallBackProcPtr SRCallBackUPP;
  133.  
  134. #define CallSRCallBackProc(userRoutine, param)        \
  135.         (*(userRoutine))((param))
  136. #define NewSRCallBackProc(userRoutine)        \
  137.         (SRCallBackUPP)(userRoutine)
  138. #endif
  139.  
  140. #if defined(powerc) || defined (__powerc)
  141. #pragma options align=mac68k
  142. #endif
  143.  
  144. struct SRCallBackParam {
  145.     SRCallBackUPP        callBack;
  146.     SRCallBackStruct    *param;
  147. };
  148. typedef struct SRCallBackParam SRCallBackParam;
  149.  
  150. #if defined(powerc) || defined(__powerc)
  151. #pragma options align=reset
  152. #endif
  153.  
  154.  
  155.  
  156. /* Recognition System Types */
  157. #define kPlainTalkSystem            'ptlk'
  158. #define    kDefaultRecognitionSystemID    ((OSType) 0)
  159.  
  160. /* Recognition System Properties */
  161. #define    kRejectedWord                'rejq'    /* the LMWord used to represent a rejection */
  162. #define kSeparationChars            'spch'    /* separation chars for current dialect setting -- use pointer to SeparationChars struct, defined in Dialect.h */
  163.  
  164.  
  165. /* Speech Source Types */
  166. #define    kSRDefaultSpeechSource        ((OSType) 0)
  167.  
  168. /* Speech Source Properties */
  169.  
  170.  
  171. /* Notification via Apple Event or Callback */
  172.  
  173. /* Notification Flags */
  174. #define kNotifyRecognitionBeginning    (1L<<0)    /* recognition can begin. client must now call SRContinueRecognition or SRAbortRecognition */
  175. #define kNotifyRecognitionDone        (1L<<1)    /* recognition has terminated. result (if any) is available. */
  176.  
  177. /* Apple Event selectors */
  178.  
  179. /* AppleEvent message class  */
  180. #define kAESpeechSuite                'sprc'
  181.  
  182. /* AppleEvent message event ids */
  183. #define kAESpeechDone                'srsd'
  184. #define kAESpeechDetected            'srbd'
  185.  
  186. /* AppleEvent Parameter ids */
  187. #define keyRecognizer                  'krec'
  188. #define keySpeechResult                'kspr'
  189. #define keySpeechStatus                'ksst'
  190.  
  191. /* AppleEvent Parameter types */
  192. #define typeRecognizer                'trec'
  193. #define typeSpeechResult            'tspr'
  194.  
  195.  
  196. /* Recognizer Properties */
  197. #define kSpeedVsAccuracyParam        'sped'    /* SpeedSetting between 0 and 100 */
  198.                                             /* 0 means more accurate but slower. */
  199.                                             /* 100 means (much) less accurate but faster. */
  200. #define kSearchStatusParam            'stat'    /* see status flags below */
  201. #define kNotificationParam            'noti'    /* see notification flags below */
  202. #define kCallBackParam                'call'    /* type SRCallBackParam */
  203. #define    kAutoFinishingParam            'afin'    /* automatic finishing applied on LM for search */
  204. #define    kMinUtteranceLength            'minl'    /* type UtteranceLength */
  205. #define    kMaxUtteranceLength            'maxl'    /* type UtteranceLength */
  206. #define    kNumQueuedUtterances        'numq'    /* type UtteranceCount */
  207. #define kForegroundOnly                'fgon'    /* Boolean. Default is true. If true, client recognizer only active when in foreground.    */
  208. #define kBlockBackground            'blbg'    /* Boolean. Default is false. If true, when client recognizer in foreground, rest of LMs are inactive.    */
  209.  
  210. /* Operational Status Flags */
  211. #define kIdleRecognizer                (1L<<0)    /* engine is not active */
  212. #define kSearchInProgress            (1L<<1)    /* search is in progress */
  213. #define kSearchWaitForAllClients    (1L<<2)    /* search is suspended waiting on all clients' input */
  214. #define kMustAbortSearch            (1L<<3) /* something has occurred (sound played, non-speech detected) requiring the search to abort */
  215. #define kPendingSearch                (1L<<4) /* we're about to start searching */
  216.  
  217. /* Recognition Result Properties */
  218. #define    kTEXTFormat                    'TEXT'    /* raw text in user supplied memory */
  219. #define kLMPhraseFormat                'lmph'    /* LMPhrase containing result words */
  220. #define kLMPathFormat                'lmpt'    /* LMPath containing result phrases or words */
  221. #define kLanguageModelFormat        'lmfm'    /* top level LanguageModel for post parse */
  222.  
  223. /* LMObject Family Properties */
  224. #define kLMName                        'name'    /* name of a LanguageModel */
  225. #define kSpelling                    'spel'    /* spelling of a LMWord or LMPhrase or LMPath, or name of a LanguageModel */
  226. #define kLMObjType                    'lmtp'    /* Returns one of LMObject Types listed below */
  227. #define kRefCon                        'refc'    /* 4 bytes of user storage */
  228. #define kEnabled                    'enbl'    /* Boolean -- true if LMObject enabled */
  229. #define kPrimitive                    'prim'    /* Boolean -- determines what shows up in search result's list of primitives */
  230. #define kFinishingFlags                'finf'    /* pass pointer to LMFlags */
  231. #define kRejectionLevel                'rjct'    /* RejectionLevel between 0 and 100 */
  232.  
  233. /* LM Object Types -- returned as kLMObjType property of language model objects */
  234. #define kLMType                        'lmob'    /* LanguageModel */
  235. #define kPathType                    'path'    /* LMPath */
  236. #define kPhraseType                    'phra'    /* LMPhrase */
  237. #define kWordType                    'word'    /* LMWord */
  238.  
  239. /* a normal and reasonable rejection level */
  240. #define    kDefaultLMRejectionLevel     50
  241.  
  242. /* Finishing Flags - used to make up LMFlags, which is used for kFinishingFlags and kAutoFinishingParam properties */
  243.                                             /* bit zero is reserved! - remove before shipping */
  244. #define kAddPauses                     (1L<<1)    /* allows user to pause between words */
  245. #define kAddRejection                 (1L<<2)    /* unrecognized words will be rejected */
  246. #define kAddNoise                    (1L<<3)    /* allows a some noise at beginning or end of utterance */
  247. #define kMakeOptional                (1L<<4)    /* contents of LM are optional */
  248. #define kMakeRepeatable                (1L<<5)    /* contents of LM may be repeated 0 or more times */
  249. #define kAddKeyword                    (1L<<7) /* only used in kAutoFinishingParam property */
  250. #define kAddWordSpotting            (kAddRejection | kMakeRepeatable)
  251. #define kDefaultFinishing            kAddPauses
  252. #define kNoFinishing                0
  253.  
  254. /*
  255.                         NOTES ON USING THE API
  256.  
  257.     All operations (with the exception of SRGetRecognitionSystem) are
  258.     directed toward an object allocated or begot from New, Get and Read
  259.     type calls.
  260.     
  261.     There is a simple rule in dealing with allocation and disposal:
  262.     
  263.     *    all toolbox allocations are obtained from a RecognitionSystem
  264.     
  265.     *    if you obtain an object via New or Get, then you own a reference 
  266.         to that object and it must be released via SRReleaseObject when
  267.         you no longer need it
  268.     
  269.     *    when you receive a RecognitionResult object via AppleEvent or
  270.         callback, it has essentially been created on your behalf and so
  271.         you are responsible for releasing it as above
  272.     
  273.     *    when you close a RecognitionSystem, all remaining objects which
  274.         were allocated with it will be forcefully released and any
  275.         remaining references to those objects will be invalid.
  276.     
  277.     This translates into a very simple guideline:
  278.         If you allocate it or have it allocated for you, you must release
  279.         it.  If you are only peeking at it, then don't release it.
  280.  
  281. */
  282.  
  283. #if defined (__NOSRTRAPS__)
  284. #define    SRINLINE(hx)    /* eat it up */
  285. #elif defined (THREEWORDINLINE)
  286. #define    SRINLINE(hx)    THREEWORDINLINE(0x303C,hx,0xAA56)
  287. #else
  288. #define    SRINLINE(hx)    = {0x303C,hx,0xAA56}
  289. #endif
  290.  
  291.  
  292. #ifdef    __cplusplus
  293. extern "C" {
  294. #endif
  295.  
  296. /* Opening and Closing of the RecognitionSystem */
  297. pascal OSErr SROpenRecognitionSystem (RecognitionSystem *system, OSType systemID)
  298.  SRINLINE (0x0400);
  299. pascal OSErr SRCloseRecognitionSystem (RecognitionSystem system)
  300.  SRINLINE (0x0201);
  301.  
  302. /* Accessing Properties of any Speech Object */
  303. pascal OSErr SRSetProperty (SpeechObject srObject, OSType selector,
  304.         const void *property, Size propertyLen)
  305.  SRINLINE (0x0802);
  306. pascal OSErr SRGetProperty (SpeechObject srObject, OSType selector,
  307.         void *property, Size *propertyLen)
  308.  SRINLINE (0x0803);
  309.  
  310. /* Any object obtained via New or Get type calls must be released */
  311. pascal OSErr SRReleaseObject (SpeechObject srObject)
  312.  SRINLINE (0x0204);
  313.  
  314. /* Traversing RecognitionResult or LMObjects */
  315. pascal OSErr SRCountItems (SpeechObject container, long *count)
  316.  SRINLINE (0x0405);
  317. pascal OSErr SRGetIndItem (SpeechObject container, SpeechObject *item, long index)
  318.  SRINLINE (0x0606);
  319. pascal OSErr SRSetIndItem (SpeechObject container, SpeechObject item, long index)
  320.  SRINLINE (0x0607);
  321. pascal OSErr SRRemoveIndItem (SpeechObject container, long index)
  322.  SRINLINE (0x0408);
  323.  
  324. /* Selecting the SpeechSource */
  325. pascal OSErr SRGetSpeechSource (RecognitionSystem system, SpeechSource *source,
  326.         OSType selector)
  327.  SRINLINE (0x0609);
  328.  
  329. /* Recognizer Instance Functions */
  330. pascal OSErr SRNewRecognizer (RecognitionSystem system, Recognizer *instance,
  331.         OSType sourceID)
  332.  SRINLINE (0x060A);
  333. pascal OSErr SRNewRecognizerFromSource (RecognitionSystem system, Recognizer *instance,
  334.         SpeechSource source)
  335.  SRINLINE (0x060B);
  336. pascal OSErr SRStartListening (Recognizer instance)
  337.  SRINLINE (0x020C);
  338. pascal OSErr SRStopListening (Recognizer instance)
  339.  SRINLINE (0x020D);
  340. pascal OSErr SRSetLanguageModel (Recognizer instance, LanguageModel active)
  341.  SRINLINE (0x040E);
  342. pascal OSErr SRGetLanguageModel (Recognizer instance, LanguageModel *active)
  343.  SRINLINE (0x040F);
  344. pascal OSErr SRContinueRecognition (Recognizer instance)
  345.  SRINLINE (0x0210);
  346. pascal OSErr SRAbortRecognition (Recognizer instance)
  347.  SRINLINE (0x0211);
  348.  
  349. /* Language Model Building and Manipulation Functions */
  350. pascal OSErr SRNewLanguageModel (RecognitionSystem system, LanguageModel *model,
  351.         const void *name, Size nameLength)
  352.  SRINLINE (0x0812);
  353. pascal OSErr SRNewPath (RecognitionSystem system, LMPath *path)
  354.  SRINLINE (0x0413);
  355. pascal OSErr SRNewPhrase (RecognitionSystem system, LMPhrase *phrase,
  356.         const void *text, Size textLength)
  357.  SRINLINE (0x0814);
  358. pascal OSErr SRNewWord (RecognitionSystem system, LMWord *word,
  359.         const void *text, Size textLength)
  360.  SRINLINE (0x0815);
  361.  
  362. /* Operations on any object of the LMObject family */
  363. pascal OSErr SRSaveLMObject (LMObject lmObject, short resID)
  364.  SRINLINE (0x0316);
  365. pascal OSErr SRLoadLMObject (RecognitionSystem system,
  366.         LMObject *lmObject, short resID)
  367.  SRINLINE (0x0517);
  368. pascal OSErr SREmptyLMObject (LMObject lmObject)
  369.  SRINLINE (0x0218);
  370. pascal OSErr SRChangeLMObject (LMObject lmObject, const void *text, Size textLength)
  371.  SRINLINE (0x0619);
  372. pascal OSErr SRAddLMObject (LMObject base, LMObject addon)
  373.  SRINLINE (0x041A);
  374. pascal OSErr SRAddText (LMObject base, const void *text,
  375.     Size textLength, long refCon)
  376.  SRINLINE (0x081B);
  377. pascal OSErr SRRemoveLMObject (LMObject base, LMObject toRemove)
  378.  SRINLINE (0x041C);
  379.  
  380. #ifdef    __cplusplus
  381. }
  382. #endif
  383.  
  384. #endif    /* __SPEECHRECOGNITION__ */
  385.